## -*- mode: html; coding: utf-8; -*-

## This file is part of CDS Invenio.
## Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008 CERN.
##
## CDS Invenio is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2 of the
## License, or (at your option) any later version.
##
## CDS Invenio is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with CDS Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.

<!-- WebDoc-Page-Title: BibEdit Admin Guide -->
<!-- WebDoc-Page-Navtrail: <a class="navtrail" href="<CFG_SITE_URL>/help/admin<lang:link/>">_(Admin Area)_</a> -->
<!-- WebDoc-Page-Revision: $Id$ -->

<h2>Contents</h2>
<strong>1. <a href="#1">Overview</a></strong><br />
<strong>2. <a href="#2">Edit records via Web interface</a></strong><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2.1. <a href="#2.1">Keyboard shortcuts</a><br />
<strong>3. <a href="#3">Edit records via command line</a></strong><br />
<strong>4. <a href="#4">Delete records via command line</a></strong><br />
<strong>5. <a href="#5">Delete all records</a></strong><br />
<strong>6. <a href="#6">Access record history</a></strong><br />

<a name="1"></a><h2>1. Overview</h2>

<p>BibEdit enables you to directly manipulate bibliographic data, edit a
single record, do global replacements, and other cataloguing tasks.</p>

<a name="2"></a><h2>2. Edit records via Web interface</h2>

<p>To edit records via the web interface, please go to <a
href="<CFG_SITE_URL>/record/edit/">BibEdit Admin
Interface</a>.  This interface will let you to add, change or
delete fields in a record.</p>

<p>If you want to change several records at once, please use the batch
command-line techniques describe below.</p>

<p>Please note that 8564 tags pointing to fulltext files managed by CDS Invenio
can't be manipulated via BibEdit. In order to modify them please use the
<a href="bibupload-admin-guide#3.5">FFT tags through BibUpload</a> or the
bibdocfile command line tool.</p>

<a name="2.1"></a><h3>2.1 Keyboard shortcuts</h3>

<h4>Basic record actions</h4>
<table border="1" width="600px">
  <thead>
    <tr> <th>Shortcut</th> <th>Definition</th> <th>Action</th> </tr>
  </thead>
  <tbody>
    <tr> <td>g</td> <td>Select</td> <td>Go to the record selection
    field</td> </tr>
    <tr> <td>Ctrl+Right</td> <td>Next</td> <td>Go to next record
	(in search results).</td> </tr>
    <tr> <td>Ctrl+Left</td> <td>Previous</td> <td>Go to previous record
	(in search results).</td> </tr>
    <tr> <td>Shift+s</td> <td>Submit</td> <td>Submit the record.</td> </tr>
    <tr> <td>Shift+c</td> <td>Cancel</td> <td>Cancel editing of the
	record.</td> </tr>
    <tr> <td>Shift+d</td> <td>Delete</td> <td>Delete the record.</td> </tr>
    <tr> <td>Shift+t</td> <td>Tags</td> <td>Toggle MARC/human tags.</td> </tr>
    <tr> <td>a</td> <td>Add field</td> <td>Add a new, empty field.</td> </tr>
    <tr> <td>Del</td> <td>Delete selected</td> <td>Deletes all selected
	fields.</td> </tr>
  </tbody>
</table>

<h4>Focused (clicked) subfield</h4>
<table border="1" width="600px">
  <thead>
    <tr> <th>Shortcut</th> <th>Definition</th> <th>Action</th> </tr>
  </thead>
  <tbody>
    <tr> <td>Tab</td> <td>Next</td> <td>Move focus to next subfield.</td> </tr>
    <tr> <td>Shift+Tab</td> <td>Previous</td> <td>Move focus to previous
	subfield.</td> </tr>
    <tr> <td>Return</td> <td>Edit</td> <td>Edit focused subfield.</td> </tr>
    <tr> <td>Space</td> <td>Select</td> <td>Select focused subfield.</td> </tr>
    <tr> <td>Shift+Space</td> <td>Select field</td> <td>Select parent field of
	focused subfield.</td> </tr>
    <tr> <td>Ctrl+Up</td> <td>Move up</td> <td>Move focused subfield up.</td> </tr>
    <tr> <td>Ctrl+Down</td> <td>Move down</td> <td>Move focused subfield
	down.</td> </tr>
    <tr> <td>Ctrl+Shift+e</td> <td>Add subfield</td> <td>Add an additional
	subfield at the end.</td> </tr>
    <tr> <td>Ctrl+Shift+d</td> <td>Remove subfield</td> <td>Remove a subfield
	from the end.</td> </tr>
  </tbody>
</table>

<h4>Input field/form</h4>
<table border="1" width="600px">
  <thead>
    <tr> <th>Shortcut</th> <th>Definition</th> <th>Action</th> </tr>
  </thead>
  <tbody>
    <tr> <td>Ctrl+Shift+s</td> <td>Save</td> <td>Save content of
	field/form.</td> </tr>
    <tr> <td>Ctrl+Shift+s</td> <td>Cancel</td> <td>Cancel editing of
	field/form.</td> </tr>
    <tr> <td>Ctrl+Shift+s</td> <td>Clear</td> <td>Clear content of
	field/form.</td> </tr>
    <tr> <td>Ctrl+Shift+e</td> <td>Add subfield</td> <td>Add an additional
	subfield at the end.</td> </tr>
    <tr> <td>Ctrl+Shift+d</td> <td>Remove subfield</td> <td>Remove a subfield
	from the end.</td> </tr>
  </tbody>
</table>

<h4>Other functionality</h4>
<table border="1" width="600px">
  <thead>
    <tr> <th>Shortcut</th> <th>Definition</th> <th>Action</th> </tr>
  </thead>
  <tbody>
    <tr> <td>s</td> <td>Selection mode</td> <td>Toggle selection mode.</td> </tr>
  </tbody>
</table>

<a name="3"></a><h2>3. Edit records via command line</h2>

<p>The idea is to download record in XML MARC format, edit it by using
any editor, and upload the changes back.  Note that you can edit any
number of records at the same time: for example, you can download all
records written by <code>Qllis, J</code>, open the file in your
favourite text editor, and change globally the author name to the
proper form <code>Ellis, J</code>.</p>

<p>You therefore continue as follows:</p>

<ol>
<li> Download the record in XML MARC.  For example, download record ID 1234:

        <pre>
         $ wget -O z.xml 'http://your.site/record/1234?of=xm'
        </pre>

    or download latest 5,000 public documents written by <code>Qllis, J</code>:

        <pre>
         $ wget -O z.xml 'http://your.site/search?p=Qllis%2C+J&f=author&of=xm&rg=5000'
        </pre>

   Note also that you can access history of records as covered in
   a <a href="#6">access record history</a> section below.<p/>

<li> Edit the metadata as necessary:

        <pre>
         $ emacs z.xml
        </pre>

<li> Upload changes back:

        <pre>
         $ bibupload -r z.xml
        </pre>

<li> See the progress of the treatment of the file via BibSched:

        <pre>
         $ bibsched
        </pre>

     If you do not want to wait for the next wake-up time of indexing
     and formatting daemons, launch them manually now:

         <pre>
         $ bibindex
         $ bibreformat
         $ webcoll
         </pre>

      and watch the progress via <code>bibsched</code>.

 </ol>

<p>After which the record(s) should be fully modified and formatted and
all indexes and collections updated, as necessary.</p>

<a name="4"></a><h2>4. Delete records via command line</h2>

<p>Once a record has been uploaded, we prefer not to *destroy* it fully
anymore (i.e. to wipe it out and to reuse its record ID for another
record) for a variety of reasons.  For example, some users may have
put this record already into their baskets in the meantime, or the
record might have already been announced by alert emails to the
external world, or the OAI harvestors might have harvested it already,
etc.  We usually prefer only to *mark* records as deleted, so that our
record IDs are ensured to stay permanent.</p>

<p>Thus said, the canonical way to delete the record #1234 in CDS Invenio
v0.1.x development branch is to download its XML MARC:

       <pre>
       $ wget -O z.xml 'http://your.site/record/1234?of=xm'
       </pre>

and to mark it as deleted by adding the indicator ``DELETED'' into the
MARC 980 $$c tag:

       <pre>
       $ emacs z.xml
       [...]
        &lt;datafield tag="980" ind1=" " ind2=" "&gt;
          &lt;subfield code="a"&gt;PREPRINT&lt;/subfield&gt;
          &lt;subfield code="c"&gt;DELETED&lt;/subfield&gt;
        &lt;/datafield&gt;
       [...]
       </pre>

and upload thusly modified record in the `replace' mode:

       <pre>
       $ bibupload -r z.xml
       </pre>

and watch the progress via <code>bibsched</code>, as mentioned in the
<a href="#3">section 3</a>.
</p>

<p>This procedure will remove the record from the collection cache so
that the record won't be findable anymore.  In addition, if the users
try to access this record via direct URL such as distributed by the
alert engine (record/1234) or via their baskets, they will
see a message ``This record has been deleted''.  Please note though
that the original MARCXML of the record stays kept in the database,
for example you can access it by:

<pre>
   $ python -c "from zlib import decompress; \\
                from invenio.dbquery import run_sql; \\
                print decompress(run_sql('SELECT value FROM bibfmt \\
                WHERE id_bibrec=1234 AND format=\'xm\'')[0][0])"
</pre>

<p>In some cases you may want to hide the record from the searches,
but to leave it accessible via direct URLs or via baskets.  In this
case the best it to alter its collection tag (980) to some
non-existent collection, for example:

<pre>
   $ wget -O z.xml 'http:://localhost/record/1234?of=xm'
   $ perl -pi -e 's,<subfield code="a">ARTICLE</subfield>,<subfield code="a">HIDDENARTICLE</subfield>,g' z.xml
   $ bibupload -r z.xml
</pre>

This will make the record non-existent as far as the search engine is
concerned, because it won't belong to any existing collection, but the
record will exist ``on its own'' and the users knowing its recID will
be able to access it.
</p>

<p>P.S. Note that the ``bibXXx'' tables will keep having entries for the
     deleted records.  These entries are to be cleaned from time to
     time by the BibEdit garbage collector.  This GC isn't part of
     CDS Invenio yet; moreover in the future we plan to abolish all the
     bibXXx tables, so that this won't be necessary anymore.</p>


<a name="5"></a><h2>5. Delete all records</h2>

    <p>If you want to wipe out all the existing bibliographic content of
       your site, for example to start uploading the documents from
       scratch again, you can launch:

     <pre>
       $ /opt/cds-invenio/bin/dbexec &lt; /opt/cds-invenio/src/cds-invenio-0.90/modules/miscutil/sql/tabbibclean.sql
       $ rm -rf /opt/cds-invenio/var/data/files/*
       $ /opt/cds-invenio/bin/webcoll
       $ /opt/cds-invenio/bin/bibindex --reindex
     </pre>

     Note that you may also want to delete the fulltext files and the
     submission counters in <code>/opt/cds-invenio/var/data</code>
     subdirectories, if you use WebSubmit.
    </p>

<a name="6"></a><h2>6. Access record history</h2>

<p>Every revision of the metadata of a record is stored in the
"history" table containing all previous MARCXML master formats of the
record.  You can access them via the <code>bibedit</code> command line
utility.

<p>To list previous revisions of record ID 1:

     <pre>
     $ /opt/cds-invenio/bin/bibedit --list-revisions 1
     1.20080319193118
     1.20080318172536
     1.20080311020315
     </pre>

<p>To get MARCXML of the revision 1.20080318172536 (record ID 1,
revision date 2008-03-18 17:25:36):

     <pre>
     $/opt/cds-invenio/bin/bibedit --get-revision 1.20080318172536 | head -5
     &lt;record>
       &lt;controlfield tag="001">1&lt;/controlfield>
       &lt;datafield tag="037" ind1=" " ind2=" ">
         &lt;subfield code="a">CERN-EX-0106015&lt;/subfield>
       &lt;/datafield>
     [...]
     </pre>

<p>To compare the differences between the two last revisions:

     <pre>
     $ /opt/cds-invenio/bin/bibedit --diff-revisions 1.20080318172536 1.20080319193118
     --- 1.20080318172536
     +++ 1.20080319193118
     @@ -4,7 +4,7 @@
          &lt;subfield code="a">CERN-EX-0106015&lt;/subfield>
        &lt;/datafield>
        &lt;datafield tag="100" ind1=" " ind2=" ">
     -    &lt;subfield code="a">Photolab&lt;/subfield>
     +    &lt;subfield code="a">Photolab SOME TEST EDIT HERE&lt;/subfield>
        &lt;/datafield>
        &lt;datafield tag="245" ind1=" " ind2=" ">
          &lt;subfield code="a">ALEPH experiment: Candidate of Higgs boson production&lt;/subfield>
     @@ -26,7 +26,7 @@
        &lt;/datafield>
        &lt;datafield tag="650" ind1="1" ind2="7">
          &lt;subfield code="2">SzGeCERN&lt;/subfield>
     -    &lt;subfield code="a">Experiments and Tracks&lt;/subfield>
     +    &lt;subfield code="a">Experiments and Tracks SOME TEST EDIT THERE&lt;/subfield>
        &lt;/datafield>
        &lt;datafield tag="653" ind1="1" ind2=" ">
          &lt;subfield code="a">LEP&lt;/subfield>
     </pre>
